.TH std::match_results 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::match_results \- std::match_results

.SH Synopsis
   Defined in header <regex>
   template<

       class BidirIt,                                             \fB(1)\fP \fI(since C++11)\fP
       class Alloc = std::allocator<std::sub_match<BidirIt>>

   > class match_results;
   namespace pmr {

       template <class BidirIt>
       using match_results = std::match_results<BidirIt,          \fB(2)\fP \fI(since C++17)\fP
                                 std::pmr::polymorphic_allocator<
                                     std::sub_match<BidirIt>>>;

   }

   The class template std::match_results holds a collection of character sequences that
   represent the result of a regular expression match.

   This is a specialized allocator-aware container. It can only be default created,
   obtained from std::regex_iterator, or modified by std::regex_search or
   std::regex_match. Because std::match_results holds std::sub_matches, each of which
   is a pair of iterators into the original character sequence that was matched, it's
   undefined behavior to examine std::match_results if the original character sequence
   was destroyed or iterators to it were invalidated for other reasons.

   The first std::sub_match (index 0) contained in a std::match_result always
   represents the full match within a target sequence made by a regex, and subsequent
   std::sub_matches represent sub-expression matches corresponding in sequence to the
   left parenthesis delimiting the sub-expression in the regex.

   std::match_results meets the requirements of a AllocatorAwareContainer and of a
   SequenceContainer, except that only copy assignment, move assignment, and operations
   defined for a constant containers are supported, and that the semantics of
   comparison functions are different from those required for a container.

.SH Type requirements

   -
   BidirIt must meet the requirements of LegacyBidirectionalIterator.
   -
   Alloc must meet the requirements of Allocator.

.SH Specializations

   Several specializations for common character sequence types are provided:

   Defined in header <regex>
   Type                      Definition
   std::cmatch               std::match_results<const char*>
   std::wcmatch              std::match_results<const wchar_t*>
   std::smatch               std::match_results<std::string::const_iterator>
   std::wsmatch              std::match_results<std::wstring::const_iterator>
   std::pmr::cmatch \fI(C++17)\fP  std::pmr::match_results<const char*>
   std::pmr::wcmatch \fI(C++17)\fP std::pmr::match_results<const wchar_t*>
   std::pmr::smatch \fI(C++17)\fP  std::pmr::match_results<std::string::const_iterator>
   std::pmr::wsmatch \fI(C++17)\fP std::pmr::match_results<std::wstring::const_iterator>

.SH Member types

   Member type     Definition
   allocator_type  Allocator
   value_type      std::sub_match<BidirIt>
   const_reference const value_type&
   reference       value_type&
   const_iterator  implementation-defined (depends on the underlying container)
   iterator        const_iterator
   difference_type std::iterator_traits<BidirIt>::difference_type
   size_type       std::allocator_traits<Alloc>::size_type
   char_type       std::iterator_traits<BidirIt>::value_type
   string_type     std::basic_string<char_type>

.SH Member functions

   constructor   constructs the object
                 \fI(public member function)\fP
   destructor    destructs the object
                 \fI(public member function)\fP
   operator=     assigns the contents
                 \fI(public member function)\fP
   get_allocator returns the associated allocator
                 \fI(public member function)\fP
.SH State
   ready         checks if the results are available
                 \fI(public member function)\fP
.SH Size
   empty         checks whether the match was successful
                 \fI(public member function)\fP
   size          returns the number of matches in a fully-established result state
                 \fI(public member function)\fP
   max_size      returns the maximum possible number of sub-matches
                 \fI(public member function)\fP
.SH Element access
   length        returns the length of the particular sub-match
                 \fI(public member function)\fP
                 returns the position of the first character of the particular
   position      sub-match
                 \fI(public member function)\fP
   str           returns the sequence of characters for the particular sub-match
                 \fI(public member function)\fP
   operator[]    returns specified sub-match
                 \fI(public member function)\fP
                 returns sub-sequence between the beginning of the target sequence and
   prefix        the beginning of the full match
                 \fI(public member function)\fP
                 returns sub-sequence between the end of the full match and the end of
   suffix        the target sequence
                 \fI(public member function)\fP
.SH Iterators
   begin         returns iterator to the beginning of the list of sub-matches
   cbegin        \fI(public member function)\fP
   end           returns iterator to the end of the list of sub-matches
   cend          \fI(public member function)\fP
.SH Format
   format        formats match results for output
                 \fI(public member function)\fP
.SH Modifiers
   swap          swaps the contents
                 \fI(public member function)\fP

.SH Non-member functions

   operator==                    lexicographically compares the values in the two match
   operator!=                    result
   (removed in C++20)            \fI(function template)\fP
   std::swap(std::match_results) specializes the std::swap algorithm
   \fI(C++11)\fP                       \fI(function template)\fP
